Po pomyślnym opublikowaniu mojego pierwszego konektora w programie konektorów Independent Publisher (konektor myStrom), postanowiłem podzielić się z Tobą moimi doświadczeniami, abyś Ty również mógł podzielić się swoją pracą z całym światem!

Przede wszystkim to naprawdę nie jest trudne! Nie wymaga żadnego programowania, a jeśli kiedykolwiek stworzyłeś własny custom connector, to praktycznie masz już wszystko wykonane! Zróbmy to więc razem, krok po kroku. Poniżej zamieściłem doatkowo film gdzie pokazuję cały proces krok po kroku:

1. Stwórz custom connector

General information

1. Nie używaj żadnej ikony. Zostanie zastąpiona przez domyślną.
2. Użyj #da3b01 jako koloru.
3. Podaj opis swojego łącznika. To jest wymagane.
4. Wybierz typ połączenia.
5. Zdefiniuj adres URL hosta — jest to główny adres URL dla wszystkich wywołań API.
6. Zdefiniuj podstawowy adres URL — czyli po głównym adresie URL, ale przed wszystkimi adresami URL zdefiniowanymi dla określonych punktów końcowych.

Security

Zdefiniuj, jakiego uwierzytelnienia używa punkt końcowy. Zdefiniuj i skonfiguruj oczywiście 🙂

Definition

I tu zaczyna się zabawa 🙂

1. Dodaj i zdefiniuj wszystkie działania
2. Dodaj i zdefiniuj wszystkie wyzwalacze
3. Dla każdej akcji/wyzwalacza określ:
4. Summary- będzie używane jako etykieta w nagłówku akcji oraz na liście dostępnych akcji (Dowiedz się więcej).
5. Description – będzie wyświetlany pod nazwą akcji na liście dostępnych akcji, a także pod ikoną info obok nazwy akcji w nagłówku (Dowiedz się więcej).
6. Operation ID — używany wewnętrznie przez definicję łącznika.
7. Visibility – w zależności od wybranej, akcja będzie się różnie wyświetlać na liście akcji (Dowiedz się więcej):
   1. none – regularny wygląd;
   2. advanced – widoczne po kliknięciu przez użytkownika „Zobacz więcej” na liście akcji;
   3. internal – niewidoczny dla użytkowników;
   4. important – widoczne jako pierwsza akcja na liście akcji.

Zdefiniuj request/ response

1. Wybierz typ operacji;
2. Podaj adres URL. Jeśli URL zawiera parametry, otocz je nawiasami klamrowymi, np. {PARAMETR};
3. Zdefiniuj nagłówki i treść zapytania/ odpowiedzi (JSON);
4. Kliknij importuj.

Ważne! Dla odpowiedzi (response) – nie określaj schematu odpowiedzi dla typu „domyślny”. Ale nie zostawiaj go pustego. Jeśli API zwraca dynamiczną odpowiedź, twórcy muszą użyć akcji Parse JSON, aby ją obsłużyć, jednak nie są dozwolone puste odpowiedzi/akcje.

Dla każdego parametru, który będziesz mieć w żądaniu/odpowiedzi:

1. Name – używana wewnętrznie, niewidoczna dla użytkownika końcowego;
2. Description – wyświetlany wewnątrz pola oraz jako opis na liście dynamic outcomes (Dowiedz się więcej);
3. Summary – wyświetlane jako etykieta nad polem, również na liście dynamic outcomes (Dowiedz się więcej);
4. Default value – nie trzeba wyjaśniać 😉
5. Is required – czy pole wymaga zawartości, czy nie;
6. Visibility – taka sama jak dla akcji (Dowiedz się więcej);
7. Location – gdzie parametr występuje w danych żądania/odpowiedzi;
8. Typ i format – określa typ i format danych;
9. Dropdown type – czy pole powinno umożliwiać wpisanie dowolnej wartości (Disabled) czy też powinno umożliwiać wybór ze statycznego lub dynamicznego zestawu wartości (Dowiedz się więcej);
10. Lista wartości statycznych lub dynamiczna konfiguracja rozwijana.

Ważne! Postaraj się zdefiniować jak najwięcej informacji. Przynajmniej pamiętaj o zdefiniowaniu Summary dla każdego parametru.

Code

Tutaj możesz napisać/wgrać dodatkowy kod napisany w C#, jeśli punkty końcowe wymagają dodatkowej manipulacji przed przesłaniem danych do przepływu w chmurze lub z niego.

Test

Musisz wykonać każdy zdefiniowany wyzwalacz i akcję. Każdy musi zakończyć się sukcesem.

Ważne! Po pomyślnym wykonaniu wszystkich metod zrób zrzut ekranu jako dowód do weryfikacji.

2. Przetestuj custom connector

Teraz musisz utworzyć testowy Cloud flow, który zawiera co najmniej 3 akcje (i wyzwalacz, jeśli jest zdefiniowany) z niestandardowego łącznika.

Ważne! Po zbudowaniu wykonaj i zrób zrzuty ekranu pokazujące, że przepływ przebiegł pomyślnie. Możesz rozwinąć akcje.

3. Zainstaluj Microsoft Power Platform Connectors CLI

Przejdź do tego adresu URL: https://docs.microsoft.com/en-us/connectors/custom-connectors/paconn-cli, aby pobrać i zainstalować interfejs wiersza polecenia Power Platform Connector.

4. Pobierz swój custom connector

Wykonaj następujące kroki: https://docs.microsoft.com/en-us/connectors/custom-connectors/certification-submission#step-4-prepare-the-connector-artifacts, aby pobrać łącznik niestandardowy. Musisz to zrobić w dwóch krokach:

1. W konsoli CMD przejdź do katalogu, w którym chcesz pobrać łącznik.
2. Wpisz paconn login, aby się zalogować.
3. Wpisz paconn download, aby pobrać wybrany łącznik z wybranego środowiska.

5. Dostosuj swój connector

Przejdź przez krok nr 3 — Add metadata z tego łącza: https://docs.microsoft.com/en-us/connectors/custom-connectors/certification-submission#step-3-add-metadata. Musisz uzupełnić informacje w pliku apiProperties.json i apiDefinition.swagger.json.

Ponadto dla każdego parametru zdefiniowanego w adresie URL żądania dodaj „x-ms-url-encoding”: „single” (lub double, dowiedz się więcej), aby zdefiniować sposób zmiany znaczenia wartości. To jest wymagane.

Ważne! Usuń wszystkie puste właściwości z definicji łącznika. Usuń również wszystkie puste odpowiedzi i działania. Zamień/usuń wszystkie znaki Unicode.

6. Sprawdź swój connector

W konsoli przejdź do lokalizacji, w której zapisano plik apiDefinition.swagger.json. Następnie wpisz: paconn validate --api-def apiDefinition.swagger.json. Przejrzyj i napraw wszystkie błędy! Wynik walidacji musi być pozytywny (Dowiedz się więcej).

Ważne! Gdy walidacja się powiedzie, zrób zrzut ekranu. Będzie to trzeci dowód na to, że Twój łącznik jest prawidłowy.

7. Dodaj plik Readme.md

To jest ostatni wymagany plik. Musisz utworzyć plik readme zgodnie z istniejącymi szablonami (Dowiedz się więcej). Ja korzystam z tego, z github. Możesz go znaleźć tutaj: https://github.com/microsoft/PowerPlatformConnectors/blob/dev/templates/readme.md.

8. Zrób fork na repo Microsoft’s

Przejdź do https://github.com/microsoft/PowerPlatformConnectors i utwórz fork wewnątrz gałęzi dev. Spowoduje to utworzenie lokalnej wersji repozytorium na Twoim koncie.

9. Otwórz Visual Studio Code i przygotuj lokalne repo

Ja używam VS Code, możesz użyć Github Kraken lub dowolnego innego klienta github. To, co musisz teraz zrobić, to sklonować repozytorium (to, które sforkowałeś, z Github), na maszynę lokalną, a następnie utworzyć nowy branch dla swojego łącznika (opcjonalnie) i na koniec dodać wszystkie pliki i utworzyć pull request do brancha dev w repo Microsoft. Gotowy? Ok. Aaaa, najpierw zainstaluj dodatek Github w swoim VS Code 🙂

1. Naciśnij F1 i wpisz git: clone i wpisz adres URL swojego forka z github.
2. Wybierz lokalizację, w której chcesz ją sklonować.
3. Po sklonowaniu otwórz go jako nowy obszar roboczy w VS Code.
4. Teraz naciśnij F1 i wpisz git: create branch, wybierz repozytorium.
5. Teraz utwórz nowy folder poniżej „independent-publisher-connectors” z nazwą swojego łącznika i skopiuj tam trzy pliki:
   1. apiDefinition.swagger.json
   2. apiProperties.json
   3. readme.md

Ważne! Upewnij się, że w Twoim commitcie znajdują się tylko powyższe trzy pliki!

1. Teraz przejdź do kontroli źródła (Ctrl+Shift+G).
2. Wpisz podsumowanie commita – jeśli jest to ostatni commit przed pull requestem, powinno to być zgodne ze wzorcem: „YOUR CONNECTOR NAME” (Independent Publisher).
3. Kliknij „Zatwierdź”.
4. Następnie kliknij „Synchronizuj zmiany” 😉

10. Utwórz Pull Request

Teraz utwórz pull request.

1. Upewnij się, że wykonujesz pull request ze swojego repozytorium i odpowiedniej gałęzi;
2. Upewnij się, że wykonujesz pull request do gałęzi dev Microsoft;
3. Nazwij żądanie „YOUR CONNECTOR NAME” (Independent Publisher).
4. Zaznacz wszystkie pola wyboru. Zanim to zrobisz, przeczytaj je oczywiście, aby sprawdzić, czy connector jest zgodny. Podaj również linki do 3 zrzutów ekranu jako dowód, że connector działa. Obrazy mogą być przechowywane na Twoim blogu lub w innym miejscu publicznie. Dowiedz się więcej, jak dołączyć obraz za pomocą języka markdown.
5. Gdy skończysz – kliknij „Create” – rozpocznie się proces certyfikacji.

I to w zasadzie tyle. Teraz musisz poczekać na kontakt z programu Independent Publisher connector. Jeśli wystąpią jakiekolwiek problemy, zostaniesz poproszony o ich usunięcie przed wykonaniem kolejnego commita i pull request.

Powodzenia!